Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

DBValue

Inherits From:	Object

Conforms To:	DBExpressionValues

Declared In:	dbkit/DBValue.h

Class Description

The DBValue class provides objects that can embody different types of data.  DBValue objects are used throughout the Database Kit to retrieve and modify arbitrarily typed values.   

 A DBValue object consists of two parts:  a value and a type.  The value and type are set at the same time, through methods such as setIntValue: and setStringValue:; the value is passed as the argument, the type is set as indicated by the method's name.  Once this information has been set, you can retrieve the DBValue's value through methods such as intValue and stringValue.  The value is converted, if possible, to the requested return type.  You can retrieve a DBValue's typeÐthe type that was named by the method that set the valueÐas a DBTypes-conforming object through the valueType method.  

The type of a DBValue object can be one of the following:

·	An object
·	A string
·	An integer
·	A single-precision floating-point number
·	A double-precision floating point number
·	NULL

The type conversion mentioned above applies only to strings, numeric values, and NULL; you can't convert an object to or from the other data types. 

The primary use the Database Kit makes of DBValue objects is to store the values that are contained in a record.  The objects are necessary because you can't examine or set a record's values directly:  You have to get a record value (indexed by property) into a DBValue object, examine and/or modify the DBValue, and set the DBValue back into the record.  Getting and setting record values is typically done through the DBRecordList (or DBRecordStream) methods getValue:forProperty: and setValue:ForProperty:.  

The following example demonstrates how to use a DBRecordList and a DBValue to modify the record that the DBRecordList is currently pointing to:

/* Create a DBValue to retrieve and modify a record value. */
DBValue *age = [[DBValue alloc] init];

/* Retrieve the value of a property from a DBRecordList. */
/* (aRecordList and aProperty are assumed to exist. */
[aRecordList getValue:age forProperty:ageProperty];

/* Modify the value and write it back to the record. */
[birthRight setFloatValue:[age intValue]+1.0];
[aRecordList setValue:age forProperty:aProperty];

DBBinder also defines a method, valueForProperty:, that returns a DBValue that contains the value of the current record for a particular property.  However, unlike with a DBRecordList, you can modify the DBValue returned by this method and so modify the record directly.

DBValues are also used to store the values of a record's key properties, and to store the value that's embodied in a DBAssociation.

Instance Variables

None declared in this class.

Adopted Protocols

DBExpressionValues	- expressionValue
- isDeferredExpression

Method Types

Creating and Freeing	+ initialize
- init
- free

Setting values	- setDoubleValue:
- setFloatValue:
- setIntValue:
- setObjectValue:
- setObjectValueNoCopy:
- setStringValue:
- setStringValueNoCopy:
- setValueFrom:
- setNull

Reporting values	- valueType
- isEqual:
- doubleValue
- floatValue
- intValue
- objectValue
- stringValue
- isNull

Archiving	- read:
- write:

Class Methods

initialize

+ initialize

Prepares the class for use.  You normally don't need to invoke this method; however, if you're creating a subclass that implements an initialize method, you should certainly send initialize to super as part of the implementation.  Returns self.

Instance Methods

doubleValue

- (double)doubleValue

Returns the DBValue's value converted to a double-precision floating-point number.  If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

floatValue

- (float)floatValue

Returns the DBValue's value converted to a single-precision floating-point number.  If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

free

- free

Frees the DBValue.

init

- init

The designated initializer for the DBValue class, init initializes a newly allocated DBValue object.

intValue

- (int)intValue

Returns the DBValue's value converted to an integer.  If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

isEqual:

- (BOOL)isEqual:(DBValue *)anotherValue

Compares the DBValue with anotherValue and returns YES or NO as their values are or aren't equivalent.  The two objects' types needn't be the same; the method will convert the argument's value to that of the receiving DBValue, if necessary, and then perform the comparison.  A DB_COERCION_ERROR exception is raised if the conversion isn't supported.

isNull

- (BOOL)isNull

Returns YES if the DBValue's value hasn't been set, or if it's been set to the null value appropriate for its type.

objectValue

- objectValue

Returns the DBValue's value.  The value must be an object, otherwise a DB_COERCION_ERROR exception is raised.

read:

- read:(NXTypedStream *)stream

Reads the DBValue from the typed stream stream.  Returns self.

setDoubleValue:

- setDoubleValue:(double)aDouble

Sets the DBValue's value to aDouble and declares its type to be a double.  Returns self.

setFloatValue:

- setFloatValue:(float)aFloat

Sets the DBValue's value to aFloat and declares its type to be a float.  Returns self.

setIntValue:

- setIntValue:(int)anInt

Sets the DBValue's value to anInt and declares its type to be an integer.  Returns self.

setNull

- setNull

Sets the DBValue's value and type to NULL.  Returns self.

setObjectValue:

- setObjectValue:(id)anObject

Sets the DBValue's value to a copy of anObject and declares its type to be an object.  Returns self.

setObjectValueNoCopy:

- setObjectValueNoCopy:(id)anObject

Sets the DBValue's value to anObject and declares its type to be an object.   Returns self.

setStringValue:

- setStringValue:(const char *)aString

Sets the DBValue's value to a copy of aString and declares its type to be a string.  Returns self.

setStringValueNoCopy:

- setStringValueNoCopy:(const char *)aString

Sets the DBValue's value to point to aString and declares its type to be a string.  Returns self.

setValueFrom:

- setValueFrom:(DBValue *)aValue

Sets the DBValue's value and type to those of aValue.  Returns self.

stringValue

- (const char *)stringValue

Returns the DBValue's value converted to a string.  If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

valueType

- (id <DBTypes>)valueType

Returns a private, DBTypes-conforming object that stores the DBValue's type.  To get a string that represents the Objective C data type from this object, you would send it an objcType message.  The following table gives DBTypes string representations of the DBValue types: 

DBValue type	DBTypes representation

object	ª@º
string	ª*º
integer	ªiº
float	ªfº
double	ªdº
NULL	NULL

write:

- write:(NXTypedStream *)stream

Writes the DBValue object to the typed stream stream.  Returns self.